Skip to content

Conversation

@vietj
Copy link
Member

@vietj vietj commented Sep 5, 2025

Introduce QUIC server/client which can be used as basis for application protocols.

While the purpose is similar to NetClient/NetServer there are a few significant differences that would make the io.vertx.core.net API reuse.

  • QUIC mandates TLS and does not support TLS upgrade
  • QUIC requires to bind a physical UDP socket on client and server prior other interactions
  • QUIC provides connections multiplexing streams
  • A connection can be closed with a reason
  • Streams can be single duplex or full duplex
  • Server load balancing operates in a different fashion

Todo

  • endpoint metrics
  • server socket load balancing using port reuse
  • application integration API for both connection level and stream level
  • datagram
  • advanced configuration
  • flush strategy
  • server client address validation
  • qlog configuration
  • documentation
  • key export
  • connection id
  • stream reset
    • wiring
    • implement error code (requires contribution to Netty)
  • uni / bidi stream support
  • codegen
  • shutdown: stream/connection/endpoint
  • transport proxy
  • ...

@vietj vietj added this to the 5.1.0 milestone Sep 5, 2025
@vietj vietj self-assigned this Sep 5, 2025
@vietj vietj force-pushed the quic-refactoring branch 5 times, most recently from b995822 to 1675ba4 Compare September 10, 2025 14:55
@vietj vietj changed the title Extract specific TCP configuration in a TcpOptions class QUIC support Sep 10, 2025
@vietj vietj force-pushed the quic-refactoring branch 4 times, most recently from 9a84e2a to 20c87a8 Compare September 11, 2025 09:03
@vietj vietj force-pushed the quic-refactoring branch 11 times, most recently from 9ac3236 to e6a643e Compare September 18, 2025 08:07
@vietj vietj force-pushed the quic-refactoring branch 6 times, most recently from eef66ea to a3a8965 Compare September 24, 2025 08:05
@vietj vietj force-pushed the quic-refactoring branch 11 times, most recently from 8336c4d to c79ddc6 Compare October 3, 2025 08:31
vietj added 16 commits October 3, 2025 11:41
Motivation:

TCPSSLOptions is an aggregate of state that carries TCP configuration (as the name says) among others.

In sight of having a NetServer being capable of using a QUIC transport, we should encapsulate the TCP portion of the state in a specific class.

Changes:

Extract the TCP portion of the TCPSSLOptions and NetworkOptions in a TcpOptions class as a transportOptions field, it is possible to get this field with a getter.

The TCPSSLOptions now delegates to the transportOptions field its getters/setters.

The Transport SPI is updated to only use the TcpOptions configuration.

The Transport SPI now only handle the TCP configuration and leaves the general channel config to the caller.
Motivation:

Our implementation has maintained a VertxSslContext wrapping an SslContext to configure a few aspects of the SSL engine. This does not seem necessary anymore since SslContext has all the necessary configuration options on the SslContextBuilder.

Changes:

Update the SslContextFactory to handle the configuration aspects VertxSslContext was implementing.

Remove VertxSslContext wrapper and configure the options instead on the SslContextFactory.
…nection

Motivation:

ConnectionBase carries a reason/timeout set of interactions for closing a connection that is superfluous for ConnectionBase since users of it are subclasseing VertxConnection.

We aim to have ConnectionBase more reusable and universal for non vertx based connections (such as HTTP/2) yet retain this for vertx based connections (HTTP/1.1, WebSocket).
Motivation:

Letting VertxConnection subclasses manage the shutdown handler gives more flexibility and is a concerned removed from the VertxConnection that focuses on its state management and control flow without caring about interactions.
…class.

Motivation:

Since only WebSocket use an effective close reason, we should move this generic part of the VertxConnection to WebSocketConnection implementation to simplify unclutter VertxConnection and keep it focus on its responsibitlies.
Motivation:

The VertxConnection relies on Netty channel close, instead it should be separate and keep channel close as short as possible.
…ionGroup class

Motivation:

NetServer and NetClient both combine a close sequence with a channel group to implement graceful shutdown of an endpoint.

We should encapsulate it to share the code between NetServer and NetClient and reuse it in Quic.
Motivation:

Quic can be properly supported since it is out of incubation from Netty, it provides a new transport for building middlewares on top of it. Although HTTP/3 is currently the only protocol specified on top of Quic, there are discussions and will to port other protocols on top of Quic.

While the purpose is similar to NetClient/NetServer there are a few significant differences that would make the `io.vertx.core.net` API reuse.

- QUIC mandates TLS and does not support TLS upgrade
- QUIC requires to bind a _physical_ UDP socket on client and server prior other interactions
- QUIC provides connections multiplexing streams
- A connection can be closed with a reason
- Streams can be single duplex or full duplex
- Server load balancing operates in a different fashion

Vert.x can facilitate the usage of Quic in the Java ecosystem by providing a comprehensive solution and explore ways of using Netty codecs on top of Quic.

This feature provides an API to interact with Quic transport as a server or a client, very much like the existing TCP socket API. It also provides an internal API to interact with the underlying Netty configuration to plugin codecs and use messages instead of buffers.

Changes:

Quic API and implementation.
@vietj vietj force-pushed the quic-refactoring branch from c79ddc6 to d3ed8e7 Compare October 3, 2025 09:41
@vietj vietj merged commit 87e28f1 into master Oct 3, 2025
8 of 13 checks passed
@vietj vietj deleted the quic-refactoring branch October 3, 2025 10:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants